conventional-changelog

What is conventional-changelog?

The conventional-changelog npm package automates the generation of changelogs based on commit messages that follow the Conventional Commits specification. This tool is widely used to maintain a clear, readable history of project changes which can be easily communicated to other developers and users.

What are conventional-changelog's main functionalities?

Generate changelog

This code demonstrates how to generate a changelog using the Angular preset. The changelog will be written to a file named 'CHANGELOG.md'.

const conventionalChangelog = require('conventional-changelog');
const fs = require('fs');
const changelogStream = conventionalChangelog({ preset: 'angular' });
changelogStream.pipe(fs.createWriteStream('CHANGELOG.md'));

Create a release

This code snippet shows how to automatically determine the semantic version bump based on commit messages. It uses the Angular preset to recommend a bump and then uses npm to update the project version accordingly.

const conventionalRecommendedBump = require('conventional-recommended-bump');
const exec = require('child_process').exec;
conventionalRecommendedBump({ preset: 'angular' }, (error, recommendation) => {
  exec(`npm version ${recommendation.releaseType}`, (error, stdout, stderr) => {
    console.log('Version bumped to', stdout);
  });
});

Other packages similar to conventional-changelog

standard-version

standard-version is a utility for versioning using semver and CHANGELOG generation powered by Conventional Commits. It automates versioning and changelog generation but with a simpler setup compared to conventional-changelog, integrating these steps into a single command.

semantic-release

semantic-release automates the whole package release workflow including determining the next version number, generating the release notes, and publishing the package. This tool provides a more comprehensive solution compared to conventional-changelog by handling the entire release process in a CI/CD environment.

lerna

Lerna is a tool for managing JavaScript projects with multiple packages, known as monorepos. While it includes functionality for generating changelogs similar to conventional-changelog, its primary focus is on managing dependencies and publishing multiple packages from the same repository.

README

Generate a changelog from git metadata

It's recommended to use high level standard-version. Alternatively, you are probably looking for the cli module. Or use one of the plugins if you are already using the tool: grunt/gulp/atom.

Usage

$ npm install --save conventional-changelog

var conventionalChangelog = require('conventional-changelog');

conventionalChangelog({
  preset: 'angular'
})
  .pipe(process.stdout); // or any writable stream

Or if you want to use your own custom preset:

var conventionalChangelog = require('conventional-changelog');

var config = require('@org/conventional-changelog-custom-preset');
conventionalChangelog({config})
  .pipe(process.stdout); // or any writable stream

API

conventionalChangelog([options, [context, [gitRawCommitsOpts, [parserOpts, [writerOpts]]]]])

Returns a readable stream.

options

See the conventional-changelog-core docs. The API is the same with the following changes or additions:

preset

Type: string Possible values: 'angular', 'atom', 'codemirror', 'ember', 'eslint', 'express', 'jquery', 'jscs', 'jshint'

It's recommended to use a preset so you don't have to define everything yourself. Presets are names of built-in config.

A scoped preset package such as @scope/conventional-changelog-custom-preset can be used by passing @scope/custom-preset to this option.

NOTE: options.config will be overwritten by the values of preset. You should use either preset or config, but not both.

Notes for parent modules

Related

• conventional-changelog-cli - cli of this module
• standard-changelog - Similar to this module but only with angular convention
• conventional-github-releaser - Make a new GitHub release from git metadata
• conventional-recommended-bump - Get a recommended version bump based on conventional commits
• conventional-commits-detector - Detect what commit message convention your repository is using
• commitizen - Simple commit conventions for internet citizens.
• angular-precommit - Pre commit with angular conventions
• commitlint - Lint commit messages

License

MIT